<title>Cornice Documentation</title>
<style>
body {
  margin:0; padding:20px; font-family:georgia; font-size:12px; 
  font-weight:normal; padding-bottom:100px;
  line-height:20px; color:black; background:skyblue; text-align:center;
}
ul { margin:0; padding:0; }
pre { margin:0; padding:0; font-size:12px; }

#ul_wrapper li { 
  position:relative; margin-left:0px; padding:0; list-style:none; 
}
#ul_wrapper ul li { 
  position:relative; margin-left:10px; padding:0; list-style:none; 
}
table { border-collapse:collapse; }

table td { 
  font-family:georgia; font-size:12px; font-weight:normal; line-height:20px; 
  text-align:left; vertical-align:top;
}
a { text-decoration:underline; color:orange; }
a:hover { color:gold; }

.pre_code {
  background:#ddd; 
}
.div_tit {
  font-size:18px; border-bottom:#777 1px solid; line-height:20px;
}
.div_header { 
  font-size:12px; background:white; border:gold 1px solid; text-align:left;
  width:898px; margin-left:auto; margin-right:auto; color:orange;
}
.div_header a { text-decoration:none; color:orange; font-size:24px; }
.div_header a:hover { color:gold; }
.div_spacing { line-height:10px; height:10px; }
.tbl_wrapper { width:900px; margin-left:auto; margin-right:auto; }
.td_left { border:gold 0px solid; width:220px; }
.td_space { width:10px; font-size:1px; }
.td_right { border:gold 0px solid; width:670px; }
.div_left { border:gold 1px solid; background:white; }
.div_right { border:gold 1px solid; background:white; }
</style>

<!--JAVASCRIPT--------------------------------------------------------------->
<script>
function load_div(div_id) {
  if (document.getElementById(div_id)) {
    document.getElementById("div_content").innerHTML = 
    document.getElementById(div_id).innerHTML;
  }
}
</script>

<!--HTML--------------------------------------------------------------------->
<div class="div_header">
<div style="margin:10px;">
<a href="cornice.html">
Cornice PHP Framework & Website Builder Documentation
</a><br>
by Inforo Software & Computer 2011
</div>
</div>
<div class="div_spacing">&nbsp;</div>

<table class="tbl_wrapper">
<tr>
  <td class="td_left">
  <div class="div_left">
  <div style="margin:10px;">
  <ul id="ul_wrapper">
  <li>
    <a href="#" onclick="load_div('div_foldstruct');">Folder structure</a>
  </li>
  <li>
    <a href="#" onclick="load_div('div_urlconv');">URL convention</a>
  </li>
  <li>
    <a href="#" onclick="load_div('div_mcv');">MCV components</a>
    <ul>
    <li>
      <a href="#" onclick="load_div('div_layouts');">Layouts</a>
      <ul>
      <li>
        <a href="#" onclick="load_div('div_lo_models');">Models</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_lo_ctrls');">Controllers</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_lo_views');">Views</a> 
      </li>      
      </ul>
    </li>
    <li>
      <a href="#" onclick="load_div('div_pages');">Pages</a>
      <ul>
      <li>
        <a href="#" onclick="load_div('div_pg_models');">Models</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_pg_ctrls');">Controllers</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_pg_views');">Views</a> 
      </li>      
      </ul>      
    </li>    
    <li>
      <a href="#" onclick="load_div('div_blocks');">Blocks</a>
      <ul>
      <li>
        <a href="#" onclick="load_div('div_blk_models');">Models</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_blk_ctrls');">Controllers</a> 
      </li>
      <li>
        <a href="#" onclick="load_div('div_blk_views');">Views</a> 
      </li>      
      </ul>      
    </li>    
    </ul>
  </li>  
  <li>
    <a href="#" onclick="load_div('div_skins');">Skins</a>
  </li>  
  <li>
    <a href="#" onclick="load_div('div_texts');">Static texts</a>
  </li>
  <li>
    <a href="#" onclick="load_div('div_xmls');">XML files</a>
  </li>
  <li>
    <a href="#" onclick="load_div('div_data');">PSO files</a>
  </li>  
  </ul>
  </div>
  </div>
  </td>
  <td>&nbsp;</td>
  <td class="td_right">
  <div class="div_right">
  <div style="margin:10px;" id="div_content">
    This is the documentation of basic features of Cornice PHP Framework & 
    Website Builder. Click any item on the left menu to show the explaination
    about that item.
  </div>
  </div>
  </td>
</tr>
</table>

<!--CONTENT DIVS------------------------------------------------------------->
<div id="div_foldstruct" style="display:none;">
<div class="div_tit">Folder structure</div>
<div>&nbsp;</div>

All entries in the folder structure of Cornice is described as follow:
<pre class="pre_code">
<div>
+ classes
  + core -- Contains core classes of Cornice
    + bases -- Contains classes used as bases for other classes of core
    + dynamics -- Contains classes extended from bases or non-static classes
    + statics -- Contains classes which have only static methods & properties
  + customs
    + bases -- Same case as in 'core', but classes defined by developers
    + dynamics -- Same case as in 'core', but classes defined by developers
    + statics -- Same case as in 'core', but classes defined by developers
+ data
  + objects -- Contains PHP Serialized Object (.pso) files
  + secured -- Contains Secure PHP Serialized Object (.php) files
+ docs
+ files
+ libs
  + codemirror -- Library for showing styled code on browser
  + extensions -- Contains extended functions
  + jquery -- jQuery core files
  + jqueryui -- jQuery UI files
  + nicedit -- Contains files of NicEdit WYSIWYG Editor
+ mcv
  + layouts -- Contains shared layouts for pages of all modules
    + models -- Model classes for layouts to access database (mostly not used)
    + controllers -- Controller classes for layouts (mostly not used)
    + views -- CSS (width/height only), JS, HTML for layouts
  + pages  -- Contains pages of modules
    + models -- Model classes for pages (used in non-static pages)
    + controllers -- Controller classes for pages (used in non-static pages)
    + views -- CSS (should not contain width/height defs), JS, HTML for pages
  + blocks -- Contains blocks which are put inside pages
    + models -- Model classes for blocks to access database (non-static blocks)
    + controllers -- Controller classes for blocks (used in non-static blocks)
    + views -- CSS (without width/height defs), JS, HTML for blocks
+ modules -- Contains XML files describing modules
+ skins
  + skin1 -- Contains global CSS, JS, HTML (mostly just 'head' tag)
    + images -- Images used by css in this skins
    + scripts -- Scripts that generate images, like CAPTCHA, etc.
  + skin(n)
+ texts
  + lang1 -- Contains HTML texts which are larger than translatable for 'lang1'
  + lang(n)
</div>
</pre>
</div>

<!--URL CONVENTION----------------------------------------------------------->
<div id="div_urlconv" style="display:none;">
<div class="div_tit">URL convention</div>
<div>&nbsp;</div>
Let say the domain and path to certain web project is 'domain.ext/some/path'.
The URL is as follow:
<pre class="pre_code">
<a href="#" style="text-decoration:none; color:red;">
http://domain.ext/some/path/modulename_pagename_param1_value1_param(n)_value(n)
</a>
</pre>
The module name, page name, parameter names, parameter values can NOT contain
any low dashes. 
<div>&nbsp;</div>

<u>Root .htaccess file</u><br>
For this to work, the '.htaccess' file at root folder 
(meaning right under 'some/path') should be similar to the following:
<pre class="pre_code">
<div>
Options +FollowSymlinks
RewriteEngine on

RewriteRule ^frontend$ /some/path/index.php?frontend 
RewriteRule ^frontend/(.*)$ /some/path/index.php?frontend/$1 
RewriteRule ^frontend_(.*)$ /some/path/index.php?frontend_$1 

RewriteRule ^backend$ /some/path/index.php?backend 
RewriteRule ^backend/(.*)$ /some/path/index.php?backend/$1 
RewriteRule ^backend_(.*)$ /some/path/index.php?backend_$1 

RewriteRule ^devtools$ /some/path/index.php?devtools 
RewriteRule ^devtools/(.*)$ /some/path/index.php?devtools/$1 
RewriteRule ^devtools_(.*)$ /some/path/index.php?devtools_$1 
</div>
</pre>
</div>

<!--MCV CONVENTION----------------------------------------------------------->
<div id="div_mcv" style="display:none;">
<div class="div_tit">MCV convention</div>
<div>&nbsp;</div>
Here in this PHP framework the word 'MVC' is called 'MCV' for its order of 
calling, a view (V) calls funtions in controller (C), and a controller (C)
calls functions in model (M); model is the base for data, so 'M' starts first.
Thus we have 'M'->'C'->'V'.
<div>&nbsp;</div>
A view contains 4 parts, XML file, CSS file, JS file, and HTML file. 
XML file contains configuration values for the view, CSS file contains
CSS definitions used in HTML, JS file contains functions used in HTML, and
the HTML file shows how the view looks like. HTML file can contain PHP code,
so in actual file, its file extension is put as '.php' instead of '.html'.
<div>&nbsp;</div>
Here in this framework, a layout contains information of how a webpage looks 
like. Its CSS file should contain only definitions for width/height and 
positioning.
<div>&nbsp;</div>
Layout is the wrapper HTML of blocks & page, a layout can contain only one
page, and thus layout is the whole thing shown in browser, and page is just
the main content in it. Layout is page dependent, meaning which layout is used 
for rendering is configured in the XML file of page.
<div>&nbsp;</div>
Note that a 'page' isn't the whole thing shown in web browser. The whole thing
shown in web browser is called 'webpage', which is the combination of 3 parts:
layout, blocks, and page. Meaning:
<pre class="pre_code">
<div>
webpage = layout + blocks + page
</div>
</pre>
<div>&nbsp;</div>
Blocks & page follow skin, but layout doesn't, so there should be only the 
definitions about width/height and positioning in the CSS file of layout.
<div>&nbsp;</div>
Some reserved properties & methods in controller classes for layouts, pages,
and blocks (meaning by NO WAY they should be redeclared):
<pre class="pre_code">
<div>
//properties in controller files of layouts, pages, blocks
$css_path, $js_path, $php_path, $model, $accessible

//methods in controller files for layouts, pages, blocks
render_html(), render_block(), render_blocks(), render_page(), get_block()
</div>
</pre>
</div>

<!--LAYOUT CONVENTION----------------------------------------------------------->
<div id="div_layouts" style="display:none;">
<div class="div_tit">Layout convention</div>
<div>&nbsp;</div>
Here in this framework, a layout contains information of how a webpage looks 
like. Its CSS file should contain only definitions for width/height and 
positioning.
<div>&nbsp;</div>
Layout is the wrapper HTML of blocks & page, a layout can contain only one
page, and thus layout is the whole thing shown in browser, and page is just
the main content in it. Layout is page dependent, meaning which layout is used 
for rendering is configured in the XML file of page.
<div>&nbsp;</div>
Note that a 'page' isn't the whole thing shown in web browser. The whole thing
shown in web browser is called 'webpage', which is the combination of 3 parts:
layout, blocks, and page. Meaning:
<pre class="pre_code">
<div>
webpage = layout + blocks + page
</div>
</pre>
<div>&nbsp;</div>
Blocks & page follow skin, but layout doesn't, so there should be only the 
definitions about width/height and positioning in the CSS file of layout.
<div>&nbsp;</div>
A layout contains 6 files (where 'example' is the place holder of layout name):
<pre class="pre_code">
<div>
+ layouts
  + models
    - shared_example_layout_model.php (model class to access database)
  + controllers
    - shared_example_layout.php (controller class for logic)
  + views
    + css
      - shared_example_layout.css (default CSS used in HTML of layout)
    + js
      - shared_example_layout.js (JS functions used in layout, usually blank)
    + php
      - shared_example_layout.php (HTML for the layout, in 'views'  folder)
    + xml
      - shared_example_layout.xml (config values of layout, usually blank)
</div>
</pre>
<div>&nbsp;</div>
The model file has the ending "_model" not to let PHP interpreter rise an 
error about class redefinition (mixed up with layout controller's class name).
</div>

<!--LAYOUT MODEL FILES------------------------------------------------------->
<div id="div_lo_models" style="display:none;">
<div class="div_tit">Layout model file</div>
<div>&nbsp;</div>
The file name of layout model file (which is placed in 'layouts/models') has 
the following format:
<pre class="pre_code">
<div>
shared_'layoutname'_layout_model.php
</div>
</pre>
<div>&nbsp;</div>
Where 'layoutname' is the name of the layout, it can not contain low dash,
and should only contain lower case characters.
<div>&nbsp;</div>
Layout is module independent, so the word 'shared' is used as the prefix
instead of module name. The word 'layout' before the word 'model' in layout
model file name is to indicate that this file belongs to a layout, not belong
to page or block. The last word in file name, 'model', indicates that this is
a model file.
<div>&nbsp;</div>
This is the example of a layout model file:
<pre class="pre_code">
<div>
&lt;?php
class shared_example_layout_model extends model {

  //default constructor
  public function __construct() {
    //
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
</div>

<!--LAYOUT CONTROLLER FILES------------------------------------------------------->
<div id="div_lo_ctrls" style="display:none;">
<div class="div_tit">Layout controller file</div>
<div>&nbsp;</div>
The file name of layout controller file (which is placed in folder 
'layouts/controllers') has the following format:
<pre class="pre_code">
<div>
shared_'layoutname'_layout.php
</div>
</pre>
<div>&nbsp;</div>
Where 'layoutname' is the name of the layout, it can not contain low dash,
and should only contain lower case characters.
<div>&nbsp;</div>
Layout is module independent, so the word 'shared' is used as the prefix
instead of module name. The last word 'layout' in layout controller file name 
is to indicate that this file belongs to a layout, not belong to page or block. 
<div>&nbsp;</div>
This is the example of a layout controller file:
<pre class="pre_code">
<div>
&lt;?php
class shared_example_layout extends layout {

  //default constructor
  public function __construct() {
    //
  }
  
  //called before rendering layout html
  public function prepare() {
    //
  }
  
  //called after rendering layout html
  public function finish() {
    //
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
<div>&nbsp;</div>
To access the corresponding model of a layout, in layout controller use the
following syntax (the model instance is auto created by Cornice):
<pre class="pre_code">
<div>
$this->model
</div>
</pre>
</div>

<!--LAYOUT VIEW FILES------------------------------------------------------->
<div id="div_lo_views" style="display:none;">
<div class="div_tit">Layout view files</div>
<div>&nbsp;</div>
There are 4 types of file placed under 'layouts/views/css', 'layouts/views/js',
'layouts/views/php', 'layouts/views/xml' respectively. These files are 
categorised under 'views' instead of 'models' or 'controllers' folders because
they indicate how a layout should be rendered, like having CSS items, HTML tags,
etc.
<div>&nbsp;</div>
CSS file for layout should NOT contain any definition about colouring,
or background, etc. CSS file for layout should contain only definitions about
width/height and positioning.
<div>&nbsp;</div>
JS file for layout is a required file, but is usually blank.
<div>&nbsp;</div>
HTML file (stored as .php) contains HTML tag and minimal PHP code, PHP code in
this type of file should be usually using just 'echo $this->something'. Where
'$this' is linked by Cornice to this HTML file; it is actually an instance of
the layout controller class.
<div>&nbsp;</div>
XML file for layout is always blank, reserved for future use.
<div>&nbsp;</div>
Example of a layout containing 1 header, 1 footer, 1 left column, 1 main
content area, full width, CSS file:
<pre class="pre_code">
<div>
.div_wrapper_wh { width:100%; }
.div_header_wh { width:100%; }

.tbl_content_wh { width:100%; }
.td_content_left_wh { width:25%; }
.td_content_right_wh { width:75%; }

.div_footer_wh { width:100%; }
</div>
</pre>
<div>&nbsp;</div>
The corresponding HTML file for layout (requires that the files for 2 blocks
'header' and 'footer' have already been created):
<pre class="pre_code">
<div>
&lt;div class="div_wrapper_wh">
  &lt;div class="div_header_wh"> &lt;?php
    <b>$this->render_block("header");</b> ?>
  &lt;/div>

  &lt;table class="tbl_content_wh">
    &lt;tr>
      &lt;td class="td_content_left_wh"> &lt;?php
        <b>$this->render_blocks("left");</b> ?>
      &lt;/td>
      &lt;td class="td_content_right_wh"> &lt;?php
        <b>$this->render_page();</b> ?>
      &lt;/td>
    &lt;/tr>
  &lt;/table>
  
  &lt;div class="div_footer_wh"> &lt;?php
    <b>$this->render_block("footer");</b> ?>
  &lt;/div>
&lt;/div>
</div>
</pre>
<div>&nbsp;</div>
For a blank layout which show only page without any block, this is the HTML:
<pre class="pre_code">
<div>
&lt;?php
$this->render_page();
</div>
</pre>
<div>&nbsp;</div>
The method 'render_page' in layout call Cornice to render requested page
or default page of module if not indicated in URL. In the case module name is
also omitted in URL, default module in config.xml will be used.
<div>&nbsp;</div>
The 2 other methods in layout 'render_block' and 'render_blocks' call the 
methods of the same name in requested page. This is explained further in
'MCV Convention >> Pages >> Views'.
</div>

<!--PAGE CONVENTION----------------------------------------------------------->
<div id="div_pages" style="display:none;">
<div class="div_tit">Page convention</div>
<div>&nbsp;</div>
Here in this framework, a page is actually the main block which shows main
information in a webpage.
<div>&nbsp;</div>
Note that a 'page' isn't the whole thing shown in web browser. The whole thing
shown in web browser is called 'webpage', which is the combination of 3 parts:
layout, blocks, and page. Meaning:
<pre class="pre_code">
<div>
webpage = layout + blocks + page
</div>
</pre>
<div>&nbsp;</div>
Page & blocks follow skin, so the names of their CSS files have the part
indicating skin name.
<div>&nbsp;</div>
A page contains 6 files (where 'example' is the place holder of page name,
and '###' is the place holder of module name):
<pre class="pre_code">
<div>
+ pages
  + models
    - ###_example_page_model.php (model class to access database)
  + controllers
    - ###_example_page.php (controller class for logic used in page)
  + views
    + css
      - ###_example_page.css (default CSS used in HTML of page)
    + js
      - ###_example_page.js (JS functions used in page)
    + php
      - ###_example_page.php (HTML for the page, in 'views'  folder)
    + xml
      - ###_example_page.xml (config values of page, NEVER blank)
</div>
</pre>
<div>&nbsp;</div>
The model file has the ending "_model" not to let PHP interpreter rise an 
error about class redefinition (mixed up with page controller's class name).
<div>&nbsp;</div>
About the name of CSS file for page, it is not always in the format of 
'modulename_pagename_page.css', this is only the default CSS file, used when the
CSS file for requested skin not found. For a dedicated skin, the following
file name format is used (where 'skinname' is the name of certain skin):
<pre class="pre_code">
<div>
modulename_pagename_skinname.css
</div>
</pre>
<div>&nbsp;</div>
The above naming format for page CSS file indicates that there can be 
multiple CSS files for a page. Usually the default page CSS file (ending with
'_page.css') will be created first.
</div>

<!--PAGE MODEL FILES------------------------------------------------------->
<div id="div_pg_models" style="display:none;">
<div class="div_tit">Page model file</div>
<div>&nbsp;</div>
The file name of page model file (which is placed in 'pages/models') has 
the following format:
<pre class="pre_code">
<div>
'modulename'_'pagename'_page_model.php
</div>
</pre>
<div>&nbsp;</div>
Where 'pagename' is the name of the page, 'modulename' is the requested module (
ie. 'frontend','backend',...), they can not contain low dashes,
and should only contain lower case characters.
<div>&nbsp;</div>
Page is module dependent, so the module name is used as the prefix
instead of "shared" prefix. The word 'page' before the word 'model' in page
model file name is to indicate that this file belongs to a page, not belong
to layout or block. The last word in file name, 'model', indicates that this is
a model file.
<div>&nbsp;</div>
This is the example of a page model file:
<pre class="pre_code">
<div>
&lt;?php
class frontend_example_page_model extends model {

  //default constructor
  public function __construct() {
    //
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
</div>

<!--PAGE CONTROLLER FILES------------------------------------------------------->
<div id="div_pg_ctrls" style="display:none;">
<div class="div_tit">Page controller file</div>
<div>&nbsp;</div>
The file name of page controller file (which is placed in folder 
'pages/controllers') has the following format:
<pre class="pre_code">
<div>
'modulename'_'pagename'_page.php
</div>
</pre>
<div>&nbsp;</div>
Where 'pagename' is the name of the page, and 'modulename' is the name of 
requested module, they can not contain low dashes, and should only contain 
lower case characters.
<div>&nbsp;</div>
Page is module dependent, so the module name is used as the prefix
instead of "shared". The last word 'page' in page controller file name is to 
indicate that this file belongs to a page, not belong to layout or block. 
<div>&nbsp;</div>
This is the example of a page controller file (note that not like layout or
block, page has 2 more required methods 'render_block' & 'render_blocks'):
<pre class="pre_code">
<div>
&lt;?php
class frontend_example_page extends page {

  //default constructor
  public function __construct() {
    //
  }
  
  //called before rendering page html
  public function prepare() {
    //
  }
  
  //called after rendering page html
  public function finish() {
    //
  }
  
  //called by layout when it needs a block
  public function render_block($block_name) {
    $block = $this->get_block($block_name);
    //assign attributes to block or call its methods
    $block->render_html();
  }
  
  //called by layout when it needs blocks for certain position
  public function render_blocks($position_name) {
    //create blocks then call 'render_html' of those blocks
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
<div>&nbsp;</div>
To access the corresponding model of a page, in page controller use the
following syntax (the model instance is auto created by Cornice):
<pre class="pre_code">
<div>
$this->model
</div>
</pre>
<div>&nbsp;</div>
To render a shared block from page controller:
<pre class="pre_code">
<div>
$block = $this->get_block($block_name,"shared");
$block->render_html();
</div>
</pre>
</div>

<!--PAGE VIEW FILES---------------------------------------------------------->
<div id="div_pg_views" style="display:none;">
<div class="div_tit">Page view files</div>
<div>&nbsp;</div>
There are 4 types of file placed under 'pages/views/css', 'pages/views/js',
'pages/views/php', 'pages/views/xml' respectively. These files are 
categorised under 'views' instead of 'models' or 'controllers' folders because
they indicate how a page should be rendered, like having CSS items, HTML tags,
etc.
<div>&nbsp;</div>
CSS file for page should ONLY contain definitions about colouring,
or background, etc. Leave the width/height & positioning to layout CSS.
<div>&nbsp;</div>
JS file for page is a required file, but is not always has contents.
<div>&nbsp;</div>
HTML file (stored as .php) contains HTML tag and minimal PHP code, PHP code in
this type of file should be usually using just 'echo $this->something'. Where
'$this' is linked by Cornice to this HTML file; it is actually an instance of
the page controller class.
<div>&nbsp;</div>
XML file for page is required, and must have contents like layout name to be
used for page, etc.
<div>&nbsp;</div>
Example of a page CSS file:
<pre class="pre_code">
<div>
.div_page { border:red 1px solid; }
.div_page_inner { border:red 1px solid; margin:10px; }
</div>
</pre>
<div>&nbsp;</div>
Example of a page HTML file:
<pre class="pre_code">
<div>
&lt;div class="div_page">
  &lt;div class="div_page_inner">
  Example page!
  &lt;/div>
&lt;/div>
</div>
</pre>
<div>&nbsp;</div>
Example of a page XML file:
<pre class="pre_code">
<div>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;page>
  &lt;title>Example page&lt;/title>
  &lt;layout>standard&lt;/layout>
&lt;/page>
</div>
</pre>
</div>

<!--BLOCK CONVENTION----------------------------------------------------------->
<div id="div_blocks" style="display:none;">
<div class="div_tit">Block convention</div>
<div>&nbsp;</div>
Here in this framework, a block is actually a content box which takes 
certain area in webpage. Like layout, block is page dependent.
<div>&nbsp;</div>
Block can be put either directly under layout or inside page. Note that 'page'
isn't the whole thing shown in browser, that whole thing is called 'webpage':
<pre class="pre_code">
<div>
webpage = layout + blocks + page
</div>
</pre>
<div>&nbsp;</div>
Blocks & page follow skin, so the names of their CSS files have the part
indicating skin name.
<div>&nbsp;</div>
A block contains 6 files (where 'example' is the place holder of block name,
and '###' is the place holder of module name):
<pre class="pre_code">
<div>
+ blocks
  + models
    - ###_example_block_model.php (model class to access database)
  + controllers
    - ###_example_block.php (controller class for logic used in block)
  + views
    + css
      - ###_example_block.css (default CSS used in HTML of block)
    + js
      - ###_example_block.js (JS functions used in block)
    + php
      - ###_example_block.php (HTML for the block, in 'views' folder)
    + xml
      - ###_example_block.xml (config values of block, usually blank)
</div>
</pre>
<div>&nbsp;</div>
The model file has the ending "_model" not to let PHP interpreter rise an 
error about class redefinition (mixed up with block controller's class name).
<div>&nbsp;</div>
About the name of CSS file for block, it is not always in the format of 
'modulename_blockname_block.css', this is only the default CSS file, 
used when the CSS file for requested skin not found. For a dedicated skin, 
the following file name format is used (where 'skinname' is the name of 
certain skin):
<pre class="pre_code">
<div>
modulename_blockname_skinname.css
</div>
</pre>
<div>&nbsp;</div>
The above naming format for block CSS file indicates that there can be 
multiple CSS files for a block. Usually the default block CSS file (ending with
'_block.css') will be created first.
</div>

<!--BLOCK MODEL FILES------------------------------------------------------->
<div id="div_blk_models" style="display:none;">
<div class="div_tit">Block model file</div>
<div>&nbsp;</div>
The file name of block model file (which is placed in 'blocks/models') has 
the following format:
<pre class="pre_code">
<div>
'modulename'_'blockname'_block_model.php
//or
shared_'blockname'_block_model.php
</div>
</pre>
<div>&nbsp;</div>
Where 'blockname' is the name of the block, 'modulename' is the requested 
module (ie. 'frontend','backend',...), they can not contain low dashes,
and should only contain lower case characters.
<div>&nbsp;</div>
Block is both module dependent, and independent, so the module name can be used 
as the prefix, also the "shared" prefix. The word 'block' before the word 
'model' in block model file name is to indicate that this file belongs to a 
block, not belong to layout or page. The last word in file name, 'model', 
indicates that this is a model file.
<div>&nbsp;</div>
This is the example of a block model file:
<pre class="pre_code">
<div>
&lt;?php
class frontend_example_block_model extends model {

  //default constructor
  public function __construct() {
    //
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
</div>

<!--BLOCK CONTROLLER FILES------------------------------------------------------->
<div id="div_blk_ctrls" style="display:none;">
<div class="div_tit">Block controller file</div>
<div>&nbsp;</div>
The file name of block controller file (which is placed in folder 
'blocks/controllers') has the following format:
<pre class="pre_code">
<div>
'modulename'_'blockname'_block.php
//or
shared_'blockname'_block.php
</div>
</pre>
<div>&nbsp;</div>
Where 'blockname' is the name of the block, and 'modulename' is the name of 
requested module, they can not contain low dashes, and should only contain 
lower case characters.
<div>&nbsp;</div>
Block is both module dependent and independent, so the module name can be used 
as the prefix, also the "shared" prefix. The last word 'block' in block 
controller file name is to indicate that this file belongs to a block, 
not belong to layout or page. 
<div>&nbsp;</div>
This is the example of a block controller file:
<pre class="pre_code">
<div>
&lt;?php
class frontend_example_block extends block {

  //default constructor
  public function __construct() {
    //
  }
  
  //called before rendering page html
  public function prepare() {
    //
  }
  
  //called after rendering page html
  public function finish() {
    //
  }
}
</div>
</pre>
<div>&nbsp;</div>
Note that before '&lt;?php' there can NOT be any character including spaces.
If some characters are mistakenly put before that, PHP interpreter will rise
error when calling to functions manupulating http-response-header like
setCookie, etc. And also note that there's no closing PHP tag, for the same
reason.
<div>&nbsp;</div>
To access the corresponding model of a block, in block controller use the
following syntax (the model instance is auto created by Cornice):
<pre class="pre_code">
<div>
$this->model
</div>
</pre>
</div>

<!--BLOCK VIEW FILES---------------------------------------------------------->
<div id="div_blk_views" style="display:none;">
<div class="div_tit">Block view files</div>
<div>&nbsp;</div>
There are 4 types of file placed under 'blocks/views/css', 'blocks/views/js',
'blocks/views/php', 'blocks/views/xml' respectively. These files are 
categorised under 'views' instead of 'models' or 'controllers' folders because
they indicate how a block should be rendered, like having CSS items, HTML tags,
etc.
<div>&nbsp;</div>
CSS file for block should ONLY contain definitions about colouring,
or background, etc. Leave the width/height & positioning to layout CSS.
<div>&nbsp;</div>
JS file for block is a required file, but is not always has contents.
<div>&nbsp;</div>
HTML file (stored as .php) contains HTML tag and minimal PHP code, PHP code in
this type of file should be usually using just 'echo $this->something'. Where
'$this' is linked by Cornice to this HTML file; it is actually an instance of
the block controller class.
<div>&nbsp;</div>
XML file for block is required, but usually blank.
<div>&nbsp;</div>
Example of a block CSS file:
<pre class="pre_code">
<div>
.div_block1 { border:red 1px solid; }
.div_block1_inner { border:red 1px solid; margin:10px; }
</div>
</pre>
<div>&nbsp;</div>
Example of a block HTML file:
<pre class="pre_code">
<div>
&lt;div class="div_block1">
  &lt;div class="div_block1_inner">
  Example block!
  &lt;/div>
&lt;/div>
</div>
</pre>
</div>

<!--SKINS-------------------------------------------------------------------->
<div id="div_skins" style="display:none;">
<div class="div_tit">Skins</div>
<div>&nbsp;</div>
The folder structure for skins is simple:
<pre class="pre_code">
<div>
+ skins
  + skin1
    + images
    + scripts
    - global.css
    - global.js
    - global.php
  + skin(n)
    + images
    + scripts
</div>
</pre>
<div>&nbsp;</div>
Plus sign indicates a folder, minus sign indicates a file. The 3 files 
'global.css', 'global.js', 'global.php' are put into all webpages rendered.
<div>&nbsp;</div>
Unlike image URL in global.css, other CSS files for layouts, pages, blocks
must use function 'skin' to render the path to image files under current skin.
Example:
<pre class="pre_code"/>
<div>
//for image
&lt;img src="skins/&lt;?php skin(); ?>/images/example.jpg"/>

//for css class
&lt;style>
.div_example {
  background-image:url("skins/&lt;?php skin(); ?>/images/example.jpg");
}
&lt;/style>
</div>
</pre> 
</div>

<!--OTHER JS----------------------------------------------------------------->
<script>
load_div("div_foldstruct");
</script>